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Bootstrap Zero 


being a record of the posts made to the Bootstrap Zero blog during RetroChallenge 2015/07 


Write it by hand 
May 31, 2015 
Say you want to write a program. You need to pick a programming language to write it in — BASIC, say. 


Then, to run it, you need a BASIC interpreter. But what if you don't have a BASIC interpreter? Then you 
need to write one. 


But a BASIC interpreter is a program, too. You need to pick a programming language to write it in — 
assembly language, say. 


Then, to assemble it, you need an assembler. But what if you don't have an assembler? Then you need 
to write one. 


But an assembler is a program, too. You need to pick a programming language to write it in. 


You could write it in assembly, or even BASIC; but since you don't have an assembler or a BASIC 
interpreter yet, you won't be able to run your assembler, and it won't be very useful to you. 


So, what's to be done? 
Write it by hand. 
Then convert it to machine code by hand. Then put that machine code into the computer somehow. 


This will be the general theme of Cat's Eye Technologies’ project for @ RetroChallenge 2015/07: 
assume there is no programming environment available on the machine, write one, convert it to 
machine code, and enter that machine code -- manually. 


We're still working out the details, but... 
Lacking appropriate physical hardware to do this on, we'll be using an emulator. 


Being most familiar with 6502 and the Commodore 64 architecture, the emulator will probably be 
@ Vice. 


If there was really no programming environment at a// on the machine, the code would need to be 
entered in a very primitive way -- setting DIP switches, for example. We probably won't go that far. But 
we will try to come up with something comparably crude for the code-entry part. 


The programming environment might not be BASIC, and it might not be an assembler; it's more likely, in 


fact, to be something like FORTH. 
Copyright ©2023, Chris Pressey, Cat's Eye Technologies. 


(Or, depending on how it goes, it might be something completely different! But it will definitely follow the 


theme of writing it by hand.) 


Why write it by hand? 
June 23, 2015 


In the previous post, | outlined the project that Cat's Eye Technologies plans to do for @RetroChallenge 
2015/07: writing a programming environment by hand. 


But | didn't go into why | chose this project. 


The reasons are fairly simple. In 2015, and in fact for decades now, software for computers has been 
developed almost exclusively with the aid of computers. 


The sheer pervasiveness of this situation might almost lull you into an impression that it has always 
been done this way. 


But, even if you don't know the history, you can logically reason that it can't possibly have always been 
done this way; in order to develop software using a computer, there needs to be software on that 
computer first. It's a chicken-and-egg problem. 


The very first computers must have had no software on them, and the software for them must have 
been developed without using a computer, and then loaded into the computer... somehow. Only after 
that point could the computer be used to develop more and newer software for itself. 


This situation, incidentally, explains the name of this blog. Getting over this chicken-and-egg 
complication is called bootstrapping, after the mythical idea that one might reach down and, grabbing 
hold of one's own boot-straps, lift oneself off the ground. The concept shows up in several places in 
computer engineering, particularly in compiler development, but even in the common process of 
powering on a computer: we say the computer "boots", which is just a shortening of "bootstrap". 


Meanwhile, "zero" refers to the fact that there is no software on the computer yet, and suggests an 
origin point; we are starting with nothing. (OK, even if that's not absolutely true, let's say we're trying to 
get as close to the "zero point of software development" as reasonably possible.) 


Or to put it another way: pen and paper is also a programming environment. 


And, since it's so much easier to develop software using a computer, it's rather a foreign environment 
these days. So let's revisit it, lest habituation to screens and keyboards dulls our imagination! 


For the next post, | hope to write a bit about the part where the code is actually loaded into the computer 
(since that's the part we're going to fudge the most, so I'd like to impart what it's like, the best | can.) 
And while July is underway, | hope to be able to update the blog regularly with photos of the handwritten 
materials. Stay tuned! 


Loading the code 
June 26, 2015 


The most “cheating” part of this project will be avoiding the actual loading of the machine code into an 
actual machine, so | feel that should describe what it would actually be like, in the real world. 


For the sake of example, assume we've already written a programming environment — the one that we 
want to put into our computer, a computer that doesn’t have any sort of programming environment on it 
yet. Assume we’ve written this program by hand, on paper... and that we’ve already converted it all into 


machine code. The first line of it might look something like this: 


INSTRUCTION HE & BINARY 
LDA #3$¢¢ AGW oP LO1l0|00| CcoCocCa 


...followed by many, many more lines. 
There are, of course, many ways to get a program into a computer — that is, into its memory. 


In the modern world, we would just open a text editor and start typing in the program. But think of how 
much hardware and software is required to support this! Decoding the keystrokes from the keyboard is 
not terribly complicated, but displaying characters on a video display is quite another matter. And never 
mind that the text editor is yet another program that someone had to write (and get into the computer 
somehow. ) 


I’ll describe a much more primitive method here. 


Glossing over some of the details, a typical memory circuit has a number of address lines, a number of 
data lines, and a read/write gate. For example, a 64 kilobyte bank of memory might have 16 address 
lines and 8 data lines. 


To locate a byte in memory, you put a binary-encoded version of its address on the address lines. To 
read that byte, you set the read/write gate to “read” and look at what value is on the data lines. To write 
a byte, you instead put the value you write onto the data lines, and set the read/write gate to “write”. 


Normally, the CPU is doing all this memory-access. But all these lines, they’re just wires with 
voltages on them. So you can do all this reading and writing by hand, using switches. 


In fact, the front panels of some of the earliest home computers had switches and lights on them for just 
this purpose, like the Altair 8800 shown here: 


And in the absence of any other hardware, this was how you programmedzd it. You flipped the switches 
to represent the binary value you wanted to write into memory, and pressed a button to write it. 


| was going to walk through this process and ask you to imagine it, but @ @retrochallenge pointed out 
the @ 1802 Membership Card, which is a kit based on the COSMAC ELF, which, like the Altair 8800, 
was programmed with front panel switches. 


So instead, you can @read the instructions for 1802 Membership Card code loading, or watch 
@ this video to see what loading code this way is like. 


And now that I’ve shown you this, there is something I’d like to point out... 


There’s a simple improvement over switches that’s fairly obvious when you think about it a bit. Instead 
of manually changing the switches with your fingers, why not have some kind of mechanical contrivance 
which sets the switches according to a pre-arranged pattern? 


Indeed, this technology exists, and you have probably heard of it: the punched card. 


At its simplest, a punchcard reader is barely any more complex than front-panel switches. When a card 
is inserted, switch contacts close where there are holes in the card, and stay open where there aren't 
holes. And then that bit pattern gets written to memory. As a bonus, the punched card serves as a 
record of the bytes that were written to memory, and can be re-used. 


If anything, it’s the technology of card punching that’s more advanced. In the example above, the card 
puncher has printed at the top, by what looks like a dot-matrix printer, the characters for the values it 
has punched holes for below. But that’s certainly not necessary; in principle, you could punch out the 
holes by hand, using a hole-punch. 


Simulating loading the code 


OK! Now that I’ve imparted to you what it’s like, I’m going to explain why I’m going to take the liberty of 
not actually doing it this way, and how | plan to fudge it :) 


This project is primarily about making a new software development environment (using the existing 
“software development environment” of pen and paper) to be used on a computer. The act of actually 
putting it there is secondary — still important for context, of course, which is why | described it in detail. 


Also, if all the computer has is front-panel switches and lights, then maybe putting a programming 
environment onto it isn’t the most useful thing you can do. Yes, it’s easier to write a program in BASIC 


instead of in machine language, but if you still have to enter your BASIC program, byte by byte, in 
binary, using switches or by punching holes, that’s still quite a bottleneck. 


My point here is that front-panel switches and punchcard readers can load code into a computer 
directly, at the hardware level. Most other input devices — keyboards, serial ports, etc. — can’t do that; 
they’re too general-purpose. To load code, they would need to work in concert with some software 
routines that interpret the input they receive. 


Ah, but a programming environment could contain such software routines! In fact, if the purpose of a 
programming environment is to make it easier to develop software, then arguably it should let you use 
these easier-to-use, general-purpose input devices for this task. 


So, since the hardware for this project is going to be emulated anyway, what | would like to do is 
assume that the machine has, along with simulated front-panel switches, some kind of simulated 
teletype attached to it. 


We'll enter the programming environment into the computer by the front-panel switches. But the 
programming environment itself will use the simulated teletype to interact with the user. 


The actual architecture will probably look something like this: 
e An emulator for a 6052-based computer (probably a Commodore 64). 


e A little program that simulates front-panel switches, reading in strings of binary digits like 
00000100 from the C64 keyboard and writing values (in this case, 4) to successive locations in 
memory. 


e A pair of machine-language subroutines for reading a line of text from, and writing a line of text 
to, the simulated teletype. In principle, we could write these subroutines so that they actually 
talked to a teletype. In practice, they'll probably be implemented with calls to C64 KERNAL 
routines for reading from the keyboard and writing to the screen. 


If that seems rather “cheaty”, well... | agree, it’s not ideal, but I’ve only got a month to finish this :) 


Since this might be the last blog post before | begin, I'll mention a few other things you can expect from 
this project. 


e The program will be designed, programmed, and hand-assembled, on paper. 

e Updates to this blog will consist mainly of photos or scans of those papers... | won’t be writing 
posts about the design. 

e | will have a hardcopy of the Commodore 64 Programmer’s Reference Guide which | will feel 
free to consult, but I’ll try very very hard not to consult the Internet. 

e | might do a little warmup first (like, “echo the lines you type in”) before starting on the 
programming environment proper. 

e The programming environment will probably be very similar to FORTH. | will definitely be trying 
to keep it small (I will have to enter all these bytes, in binary, at the end!) while aiming to make it 
easier to program with than assembly. 


e The programming environment won't use any features of the C64 except for those two KERNAL 
routines to simulate a teletype. 


e | won't hesitate to save the emulator’s state while entering the code, so | don’t have to do it all in 
one sitting. But... I'll try very hard not to abuse that feature, to e.g. “undo” entering wrong code. 
(This suggests the programming environment should contain some kind of debugger...) 


And, er, that’s it! Can’t wait to start! 


The warm-up 


July 3, 2015 


BEFORE EMBARKING ON OUR MAIN PROJECT | 
WE'RE GOING TO DO A LITTLE WARM-UP: 


DESIGN AN “EcHO” PRoqgramM 
FOR THE SIMULATED “TELETYPE 


* COPE IT, BY HAND, IN 6S0a ASSEMBLY 


* HAND-ASSEMBLE |1T TO MACHINE Cope 
CIN HEXADECI(MAL) 


¢ HAND-CONVERT THE MACHIWE Cope 


To BINARY 
* HAND-ENTER “THE BINARY Code 
USING 
SIMULATED 


FRONT - PAWEL 
SwIiTcHES 


START: 


WARM - UP. 


READ LINE 
FROM TTY 


WRITE LINE 
SFY 


JSR REAO_ TTY 
JSR WRITE_TTy 
IMP START 


READ _ TTY: 
L 00° : 


WRITE _TTY: 


L.40?: 


LINE : 


LOY 
JSR 
STA 
INY 
CMP 
BNE 
RTS 


LDY 
LDA 
JSR 
INY 
CMP 
BNE 
RTS 


#399 
CHRIN 
LINE, Y 


#$ 9D 
Loop 


#$ OD 
LINE, Y 
CHROUT 


+$ OD 


LOOY 


(56 bytes of RAM) 


$ FFCF 


Carriage return 


$§ FFOo 


$cdop 


$8104 
$i ¢3 


$1 $6 
$1 #9 
8198 
SIGE 
Sri 
sila 
$u4 
SIG 
Zii7 
$1lq 
Frc 
SiiF 
Riad 
$laa 
$1a4 


Ise 
TSR 
TMP 
LOY 
ISR 
STA 
INY 
cue 
BNE 
RTS 
LbY 
LOA 
JSR 
INY 
CHP 
BNE 
RTS 


$ 8169 
$8117 
$8ige 
#9 
Serer 
$Cog¢g, Y 


#390 
$FS 


#¢ 
$¢996, 1 


SFFD2 


4$9D 
SFS 


g2 $1 
17 $I 
GO $1 
oo 

CF FF 


O¢ co 


gD 
FS 


$p 
o¢ co 


DA FF 


gD 
FS 


octo0000 
0°l00000 
C1lool1og 
[6160 0000 
0o|0 cc00 
[ool ool 


1100 1600 
1Leo100l 
tLol o0o00 


O1L0 0000 
[olo 0000 
JOll loo; 
6010 0060 
[loo 1000 
Il OO eo] 


l1Lol 0000 
6110 o600 


0000 Il0o/ 
cool oll 
60000000 
Ooceo0c00 
[loos 
00000000 


0000 [lol 
ILL otot 


00000000 
00000000 
[16] Coto 


oooo llol 
LitT ote 


All written! Now, to load it (see Loading the code above for details on this)... 


1000 coo[ 
loco coo] 
lococecoo| 


terhaeced 
[100 0000 


1100 6000 
occa 


bby 


SUCCESS! 


"ECHO PROGRAM IS 37 BYTES. 
THAT’S 296 BITS. 


| NEARLY MADE Q MISTAKES, BUT 
CAUGHT THEN. 


“THE MAW PROJECT witt BE mucH 
LONGER THAN THIS, THOUGH. 


WHICH PROMPTS ME To RE-THINK 
THINGS A BIT... 


DESIGN FoR 
FoR THOID 


FORTHOIO IN 
ASSEMBLY 
LAN GWAGE 


ORIGINAL PLAN 
WAS SomE THING 
LIKE ‘THIS. 


FORTHOID 
IN MACHINE 
CODE IN HEk 


FORTHOID 
IN BINARY 


6sg2 


IN BASIC 


REVISED PLAN IS SOMETHING LIKE THIS. 


eMONI TOR 1S ~ 280 BYTES 
*CAN ENTER CobE IN HEX 
“MUST Stit HAND-ASSEMBLE 
CAN REVIEW Cope once ENTERED 
-FoRTHeID CAN RE-USE 
RouTINEsS PRESENT IN 

THE MONITOR (@.5. TTY \/o) 
*IN CASE | DON’T FINISH THE 
FORTHOID... A MONITOR STILL 


COUNTS AS A PROGRAMMING 
ENVIRONMENT / 


EMULATED 
6592 


DESIGN For 
MONI ToR 


MONITOR IN 
ASSEMBLY 


ASSEMBLY 
LAWGVAGE 


FRONT-PANEL 

Swi TcHes 
SIMULATED 
IN BASIC 


A better front-panel simulator 


July 5, 2015 


One thing that disappointed me slightly during The Warm-up was that the simulated front-panel loader 
was not terribly realistic. It lets you backspace to erase bits you’ve typed in, and it leaves a “paper trail” 
of values you've entered, on the screen. It occurred to me that it wouldn't be too difficult to write 
something that simulates a front panel better, so that is just what | did. 


The front-panel simulator below works a lot like the 1802 Membership Card front panel (see Loading the 
code for more details on that.) 


The screen shows an approximation of 8 LEDs and 8 SPST switches that would be connected to the 8 
data lines on a real front panel. 


The keys on the bottom row of the keyboard move each switch down; the keys in the 2nd-to-bottom row 
move each switch up. (In an effort to be more realistic, they are not toggled by a single key.) 


Pressing Return causes the binary value selected by the switches to be written to the current address in 
RAM. That value is then reflected in the LEDs. 


qt ttt 


Other simulated buttons (not show in the Ul) are 


e =, which advances the address by one (you typically press this every time you are happy with 
the current byte you have written, ) 

e &amp; which resets the address to the beginning of memory (which can be used to review the 
bits you’ve entered by stepping through them with = and watching the LEDs), and 

e ! to execute the machine code at the current address. 


| plan to use it to enter the machine-code monitor program I’m writing (more on that in a future post.) 


l’ll put the code for this front-panel simulator (and other code from this project) in a repository on Github 
at the end of the month (or earlier, if someone requests it.) 


Cheatsheets and chickenscratches 
July 6, 2015 


| decided, while | was writing all this code by hand, | might as well also write out some stuff about 6502 
programming that | can never remember when | need it. 


GSO2 CONDITIONAL BRANCHES 


THE OPERAND OF A CONDITIONAL BRANCH (IS A 
RELATIVE AppREsSS, GIVEN AS A SIGNED BYTE 
ENCODED [IN ‘Two'S COMPLEMENT. THE ADDREsS 
IS RELATIVE To “THE INSTRUCTION FoLLOWING THE 
BRANCH, THUS, -2=$FE Witt BRANCH To ITSELF, 


WHEN COMPARIN 
G SIGNED BYTES, CHEeeK 
CARRY FLAX TO TEST FOR RELATIVE eel 


LDA 
CMP 
Bcc 


LDA 
CmP 
BCs 


LDA 
CMP 
BEQ 
BCS 


FOO 


#496 
FOO_LT.6 


BAR 
#$ Bo 
BAR_GTE_G 


BAZ 
#496 
BAZ_€Q_6 
BAZ_GT_¢ 


‘TWO TECHNIQUES FoR 
SHORTENING MACHINE CoDE. 


1. FALLTHROUGH 


FOO: BLAH Food: BLAH 
BLAH BLAH 
IMP BAR — 

BAR: BLAH BAR: BLAH 


BLAH BLAH 


FOO: BLAH Foo: BLAH 
BLAH sae BLAH 
IMP BAR 


EASY To REMEMBER BUT EVEN EASIER To Loox UP... 


8 
q 
A 
B 
G 
D 
e 
= 


Sketches of the design and code for the machine-language monitor. It was basically written three times; 
once in pencil, once with a ballpoint pen, and the final version (not shown here, coming soon!) with 


fineliners. 


wane Sw 
> Rare | 
8 Ty 


| ffao Lwek. 
q fRom TTY 


ee 
. 


‘ef Tia Lime fT 
wh Geke ser 
| , 


A 
Cha Line | > es 
writ Tener 


weit TTY 


* * @&@e ee & 


*. 
. 
’+. 
= 
“\ 


WR TE _ ANBBLE WRMIE CHAR wR TE _ For 


avd t4ge LOY Lie pra Loa 39D 
TAY thre. JME WRITE. CHAR 
LoA Htxmans, ¥ STA Liwe ¥ 
Loy twp It 
SA Lint, ¥ ih Lin€ _ PR 
|NY¥ 
St UNE Pe - 
RS 
Jer wRITE_ (aa 

writ _ gre _ x WRIE_ Prent? | vistare Werte _fhorer 
XA LOX ADk-We TR REA. TTY 
USR JSR wRITE_€Y1E_» LDA Line 
LSR Lox ApRLo cue #°A" 
LSR wd DIR VETE BY TE_y INE WET 
L5R , RDA ¢ "3° Jue SET_ApOR 
JSR VRE _1VB 5H WRITE. cHae NEXT: cpr bp" 
TxA : ars fee ExT 
an nietie SMR WEE Cot “ 


ISR WHITE ERR 
JP DiStAtcH 


READ~ (HAR. 
LDY Liw€_f ik 
LOn LIM, Y 


1a 
STY Lwe tw 


RIS 


PARSE _ HEA: 
Loy #¢ 
coots Cap HEsOIAITS, ¥ 
met fis ee ais 
ALC 
BCC Lon? 


6.0 + 
SMP (Ave 10) 
Ris 


foelouk wf 


REAO_ Brre 
TSR = Ktao_chpr 


1 L TY; Art 


SAR Thue 
JSR READ Cpr 


WR. PARSE _HEw prea 


coors OP Tint cae 
RS 


SET. ACR 
LOA #49) 
STA Liwl_Pie 


TSR PEAO_ BRE ge 


Ste Ape ty 
JR REAL EVE 
Stp AOR_LO 


ren. RTS 


WRITE. MEM: 


Ist REAO_BYTE 
we Cost 
ers 
cor Sta (ADR. LO) 
HEE 
LRA AOR_LO 
| Aoe #! 


WC -AOR 4 Sy KOR_Lo 


LRA AOR 44) 
AO “p 

Ste ADR) 
TOP WIE oem 


$ 


ECs 


- 


Low: 


PO conr 


R66 cont 


tre 


Rta oft: 


Loy 441g 

LOM ( AoR_10) _ 
JO5e WRTTE BYTE x 
TH Wle_poR 

per 

BNE Loo? 

TSR vARTE pe 


STR VATE ety 
RTS 


READ_ CHAR: 


LOY LINEOFF 
LDA LINE, Y¥ 
INY 
STY LIn&. oFF 
RTS 


> omtpul ‘ A: cher 


} increases Line Afs.t 


- naan ne Ts 


~ PARSE 
READ HEx : LO. pInpal « Az char 
L ooP: MP E 5, ¥ > owtpst A= hex valae 
BR 
v 
ExQiai TS 
Ee 
DEY 
PARSE HEX. LOY #9 aw 
LooP! CMP HEXDIGITS, Y a als NG 
BNE NExT - 3 Se 
Ty 17 war lon 
=A a en 
NEXT: INY 
CRY #fIo oe 
BNE Loor wc. 
Coa #6 "> 24 
RTS wer 14 
ow =#86§ 
iT 


REAO_ BYTE: 


REAO_ BYEX : TSR REAC cHAR 
TMP PARSE_HEx 


READ_ BYTE: TSR REAO HEx 
ASL (x4) Aso 
STA TEMP_A 
JSR READ_HEX 
ORA TEMP_A 
RTs 


SET Aone : JSR READ BYTE 
STA ADDR-HI 
JsR RKEAD_ BYTE 
STA ADPR. LO 
RTS 


—— 
WRITE. NY6: 


WRITE. CHAR: 


OUTPUTLN TTY: 


SA TEMP PHA 
WRITE_NYGBLE JSR 
LOA—Teete-A- 23290 PLA 
LSR 

LSR 

LSR 

LSKR 

TMP WwRITE_yre6ce 
PHA 

LSR «4 

TSR WRITE _N46 

PLA 

IMP VRITE NYS 
Any OF 

“TAY 

LDA HEKxDIGITS, Y 
ome WRITE CHAR 
LDY LINE_orr 
STA LINE, Y 

INY 

ST¥ Ltée oFF 
RTS 

LDA #cR 

TSR WRITE_CcHAR 
TMP 


ov TUT TTY 


or Line -oFF 
WRITE_ MEM: LpA LINE, Y 


Cue  #0R 
BNE CONT 
RTS 

CONT: TsR READ_BYFE 
STA (Avo) ¥ 
ISR  \NCR_ ADDR 
JmMP wRITE_mMemM 


<— Lor +e 


INCR_ ADOR : Cis 
LDA AvoR_LO 
Apc #92 | 
STA APOR-LO 
LOA AdPR-HI 
Aoc #¢g¢ 
STA ADDR HI 
RTS 
oot 

REAO_ MEM: Lox #BI¢ 


. a— Lov 4 
L oof caeene LDA (AopR), "7 


TSR wRite BYTE 


CEF TsR InNCR ADDR 
Ese DEX 


BNE Loof 
THR sMffemserY OUTPUT _THy 


LDA #2 
Swe LIme_oFF 
WRITE_PeomeT : LDA AOR-HI 
TM WReieE _BrE 
LA ADR-Lo 
TSR WRCTE_BYTE 
OMP OUTPUTLN_ TTY 


M Emory 
ws 
$ Coo LINE 
3 FE AooR, Apor-Lo 
$ Fe AODR. 1) 
; FD TMP _A 
FE LINE oF Fr 77 ateo jor 
S $4D 
_ $7 Ofarow! 
<4 & $57 


1g 


SITU-MON 


July 9, 2015 


OK, LET'S DESIGN & write A SIMPLE 
PROGRAMMING, ENVIRONMENT —— A 
MACHINE-LANGVAGE MONITOR. 


(A.K.A. DEBUGGER. NOT To BE CONFUSED 
WITH A VIDEO MONITOR, OF CouRSE.) 


JT WILL LACK MANY FEATURES OF A 
“REAL” MONITOR, BUT IT WILL LET US: 


* ENTER BYTES IN HEXADECIMAL AND 
WRITE THEM )NTO MEMORY 


* INSPECT THE CONTENTS OF MEMORY 
AS HEXADECIMAL 


» CALL MACHINE-LANGUAGE ROUTINES 


AND IT WILL BE SMALL ENOUGH ‘THAT 
PLL BE ABLE To ENTER IT, IN BINARY, 
USING FRONT-PANEL SWITCHES, WITHOUT 
GOING MAD. MAY6E. 


SITU - Mon, 


Svus 


WRITE 
PROMPT “To TTY 


READ LINE 
FROM TTY 


PARSE aoor 
FROM LINE 
5 READ © BYTES 
FROM ADDR, 
WRITE To TTY 


50, WELL NEED: 


» A MAIN LOOP WITH Cove TO DISPATCH 
TO THE VARIOUS MONITOR COMMANDS 
(FOUNTAIN PEN) 


* ROUTINES To PARSE THE LINE THE USER 
ENTERED, FOR HEX DIG(TS ETc. CGREEN) 


* ROUTINES TO FORMAT OUTPUT FoR THE 
USER, AS HEX DIGITS ETC. (BLUE) 


* ROUTINES TO “TAKE INPUT FROM, AND SEND 
OVTPUT To, THE VIRTUAL TELETYPE (PURPLE) 


+ THE MONITOR COMMANDS “THEMSELVES (RED) 


» SOME MISCELLANEOUS UTILITY ROUTINES 
(FUSCHIA OR WHATEVER THIS IS) 


NOTE THAT THE CODE |S NOT COMMENTED (except 
twhere T’ve made last-minute alterations) BUT EACH 
ROUTINE SHOULD BE SIMPLE ENOUGH To Follow 
FOR ANYONE WHO KNowS 6S@2 ASSEMBLER. 


MAIN. LOOP: 


DISPATCH: 


NEXT: 


NEX T: 


NEXT: 


NEXT: 


JSR 
JSR 

LDA 
STA 

JSR 
MP 


LDA 
cmp 

BNE 

TMP 

CMP 

BNE 
JMP 
CMP 
BNE 
IMP 
CMP 
BNE 
JMP 
RTS 


WRITE _ PROMPT 


INPUT_TTy 
#1 

LINE _PTR 
DISPATCH 
MAIN. Loop 


LINE 
#°A 
NEXT 
SET.ADDR 
#'M 
NEXT 
DUMP _ MEM 
#° W 
NEXT 
WRITE. MEM 
+°G 
NEx T 
(ADDR) 


A.K.A. LINE. OFF 


A.K.A. READ MEM 


READ_ CHAR: 


READ _HEx: 


PARSE _ HEX: 
Loop: 


NExT: 


READ. BYTE: 


LDY LINE. OFF 
LDA LINE, Y 


INY 


STY LINE Torr 


RTS 


JSR 


REAO_ CHAR 


Pallthreu ah 


Loy 
CHP 
BNE 
TYA 
RTS 
INY 
CPY 
BNE 
LDA 
RTS 


JSR 
ASL 
ASL 
ASL 


#409 
HExOIGITS, Y 
NEXT 


#$1¢ 


LooP 


#9 99 


READ. HEX 
A 

A 
A 


ASL A 


STA 
JSR 
ORA 
RTS 


TEMP_A 
READ. HEX 
TEMP_A 


WRITE. BYTE: PHA 
LSR 
LSR 
LSR 
LSR 
JSR WRITE HEX 
PLA 
Fall through 

WRITE —HEx: AND #¢6F 
TAY 
LDA HEXDIGITS, ¥ 
Fallthrough 

WRITE — CHAR: LDY LINE. oFF 
STA LINE, Y 
INY 
STY LINELoFF 
RTS 


> > 


WRITE _ PROMPT: 


OUTPUTLN TTY: 


OUTPUT. TTY: 


Loop: 


INPUT_TTY: 
LooP: 


LDA 
STA 
LDA 
JSR 
LDA 
JSR 


4300 
LINE_oFF 
ADDR. H[ 
WRITE_ BYTE 
ADDR_LO 
WRITE_BYTE 


Fallthrough 
LDA #¢oD 


JSR WRITE CHAR 


tall through 


LbY 
LDA 
JSR 
INY 
CMP 
BNE 
RTS 


LoY 
JSR 
STA 
INY 
cmp 
BNE 


#399 
LINE, Y 
CHROU T 


#$ OD 
Loop 


#399 
CHRIN 


LINE, Y 


#$OD 


Loop 


FP —eHReye Fe 
STA LINE, Y 
SMP CHROUT 


< 


for safety 
during WRITE _MEM 


4 


P — 


= a 


n 


as 


4 


g 


rf 
i & 7 
i 
Eta, 
Si 
ae 


ac 
nn 2 
- 
- 


NOW, DATA... 


LINE WILL BE THE SAME AS IN THE 
WARM-UP: $CGO¢P 


THERE ARE ONLY 4 OTHER MEMORY LOCATIONS 
THAT ARE USED, AND WE CAN PUT THEM IN 
THE ZERO PAGE TO KEEP THE copE SMALL. 


ADDR HAS ITS Low BYTE AT $FB 
AND ITS HIGH BYTE AT $FC 


TMP.A IS STORED AT....... $FD 
LINE_OFF 1S SToRED AT.... SFE 


WITH THESE CHOICES, THE SIZE of THE 
CODE CoMES TO... 


A50 BYTES! 


THAT'S 2,000 BITS! 


THAT’S DOABLE... | THINK... 


$Bide 
SIe¢3 
W866 
$103 
BIDA 
SigD 
Big 
8113 
aus 
BIT 
SIA 
gue 
Sle 
gal 
$123 
£125 
Firs 
BI2A 
Giac 
iar 
$13¢ 
$132 
B35 
Bi3¢ 
$138 
$139 
i386 
gi3D 
s14¢ 


MAIN 


prise 


75R $813 26 73 $I 
IsR $%94 a¢ WH TI 
LoA $$61 | Ad #1 
STA $FE gS FE 


TsR $ti¢ Ce 


IMP $318 uc gg # 
LDA Scag AD oe 6¢ 
cmp #$4I ca 4 
BNE $¢3 dg 3 
IMP $BLAT7 uc AT BL 
CMP #$4D cz 4D 
BNE $¢3 De O3 
IMP $8182 uc Ba SI 
CMP #$57 cq $7 
BNE $93 De 3 
IMP $eic4 4c Cy 8 


CMP #947 ca 47 
Bue $¢3 te 93 
zoe ($o¢Fs) Gc FB og 


RTS cé 
Loy $Fe AY FE 
Loa feog¢,y 89 ¢ co 
ny es 

STY $FE 94 FE 
RTS | oF 


IsR $9139 «as 3d 81 
Loy #$¢ef Ass 
Cue $fiE¢,Y) De EF 8 
BNE $¢a DS ga 


ocbeoooeo 
Ool| Cooed 
LOLO ces 
Loco Slol 
Oc1g ooe6 
O109 61900 
19101801 
1100100! 
irol oeoo 
Soleo tics 
[too 1co7 
fies sooo 
eiodi3c.8E 
1reoloel 
{Lol cooe 
cleo too 
trootcel 
to] oooo 
ouocileg 
otioaces 
jor Oo C1co 
101, 108) 
1100 jooo 
leeoo1oo 
Olloo0co0 
CoClo9o000 
io10 coco 
trol toofr 


[fot Oooo 


Ontootl 

loo olee 

Ooocoeo| 

Lilies 
Ooo looeo 
oe0o00c0 
Oseoseco 
© fooces| 
Cece 
loreornms 
oleo ito] 
Cooo cel 
yor ooo 
Syot oret 
oosocotl 
1 1Eeeeieo 
Ocrooott 
eooc%ooll 
tettotl 


Hett tito 
$000 0000 


tiiriehe 


OO coco 
Ooadece 
ILLOLoey 
o°eoe0l0 


1000 See! 
[occoco| 


(eooo ooo] 
1Oee Coot 
Iroooece 


[ove oreo! 


looceee![ 


1oog ooo! 


oocons0e 


11000000 


jococce! 


loooocal 


wh. 8Y. 


TYA 
RTS 


Iny 

cry #$1¢ 
BME $F 
Loa A089 


RTS 

Tsk $9139 
ASL A 
ASL A 
ASL A 
ASL A 
STA 4FD 
TSR $9139 
ORA $FD 
RTS 


LOY $Fe 


34«Bh 


oY BI 


loollooo 
olloeocoo 
eel eco 
[icoee00 
1tOl coco 
1OLoOloS) 
OLLoOe%e00 
00100000 
S000 lee 
Cocoo loc 
Oceo [oro 
Oooetoice 
[coociot 
Colo oces 
Oooe oles 
o11ccoese 
OL6CO [ooo 


Sron cece 
Sisco 
eliteces 
PSO coon 
ooo eooo 
Oto 19080 
Cold ioe 
1olo jooo 
1olf tool 
1oto ofoo 


{ool loel 


ioc loco 
looc 0100 
Oe C280 


cool oceo 
11ie16o 
60000660 


Scott lool 


tetgricl 
eoutcoot 
lostirot 


oleciole 
Sleciolo 


6 feo leoto 
oleolclo 
SPlcoleo 


Cooolttt 


CLIGlool 
tititite 
00 C96 800 


cacratis 


loce ooo! 


[eeooor) 


taccece! 


1e000 Co| 


t1iceOo08O 


Wa. Pe. 


OfiK 


oe my 


WwetTY 


LDA #00 
Sv! $FE 
LDA $Fc 
TSR $8158 
LDA $F6 
ISR $3158 


Tsk $si4c 
STA SFR 
RTS 

Lox S41¢ 
LoY #$¢¢ 


£3 


3a 


tole 1001 
O00 Olol 
loro clel 
c610 0000 
lolootel 
Ole occo 
foto lect 
O18 o#00 
{olo e606 
1OLlt oor 
po1ocooe 
tioeolaes 
hooey 
tlel oooo 
Olle oooo 
Lolo aco 
S016 6 o60 
10011 der 
1100 1eeo0 
11Oetool 
11010000 
1001 | ool 
100 1100 
6010 6000 
locoootes 
Pole e000 
loocolo| 
olleceoo 
[ole oolto 
Icio ccoe 


Sooo oe co 
Tete thd 
yier oo 
o1el tot 
Liyt vot 

oL1ol lon 

coootlol 

oyio tole 
COesoco0s 
eoocscso 
troroote 


Oooo 110! 
ttttotor 


ocecocsooes 
yicornrt 
ocog cago 


cooorel 
Lit Lorol 
ooooc000 
loloewo 
Oloolioo 
ritliiee 
Oleo 1190 
Tetatore 


Ocol Gece 
cosoooeo 


fooc osol 


loee ocol 


{oco cool 


troc cone 
fierrrns 


reeset 
l1c0O e600 


ileoodoo 
teaeroel 
tooocoo!l 


foee cool 


$BiBC 
aes 
S88 
IBE 
SibF 
Sicl 
Fick 
SICK 
Rica 
ICs 
Fico 
Bice 
BID) 
$ID3 
Bips 
Bing 
$108 
Sipe 
BIDE 
tite 
TIED 
TIES 
Biec 
Sies 
SIET HEM, 


WE. 


LOA ($96), Y 
sR $ose 
TSR $fiDB 


SIDS 


lolloool 
Sotoccoe 
Oe10 0000 
11e6cto1o 
1101 Oceo 
Sloe lice 
Lo16 Olce 
loll toot 
{Looleel 
[tel oeoo 
Clio ooeS 
Oclocesso 
LOle8 co00 
1001 Ose; 
Oo1o C080 
Sico lies 
Ooo] todo 
leoioorol 
O10 lool 
1000 Ciel 
106 Clol 
Olle lool 
looeolol 
O1LO e600 
Coil cooo 
Ooctl cool 
Coll Go10 
Coll oot 
Sell o1ee 
Oollolel 
Coll aite 
ooo 
Oon tooo 


Heittorr 
Slot roi 
Lioliouw 


tret oon 
1000 Sce1 
ittitto 
OoO0C ceed 
ooos|icl 
Scoooeol 


Cleo lice 
Cooeeoeo 
titttoue 
troltowl 
od oleo 


tlitiotl 
Oocovccoo| 
ittttow 
Clerqreo 
fete Tole) -le] 
tiiitteo 


| 060 coe! 
ldo coco! 


loco cool 


tlocoreeo 


loce ooo | 
lees ooo! 


Ootlioel 
Oloccoo( 
Sjccacio 
Sjoooe!l 
O1eooios 
Oleooiot 


oweoolto 


a a 


| love bits. Bits are great when you’re coding and you want 
2,000 of something 

July 12, 2015 

(with apologies to Mitch Hedberg for the title of this post) 


Right! So almost as soon as | finished writing the code for SITU-MON, | started entering it into the 
emulated Commodore 64, using the simulated front-panel switches. At first this was in dribs and drabs, 
a few bytes here, a few bytes there. 


¥ VICE: C64 emulator —_ + 


| won't bore you with thousands of screenshots; it all looked basically as described in A better front- 
panel simulator, above. (And for what it would look like in the physical world, watch the video on the 
Loading the code post.) It’s not difficult, exactly, it’s just tedious and fatiguing. 


Finally, | had entered all 2,000 bits, and | reset the address to the beginning, planning to review the bits | 
had entered to confirm they were the same bits that were written on the paper. 


To my considerable surprise, they were completely and utterly different bits than on the paper. They 
were nothing like what | entered. 


Then | realized what had happened. The SITU-MON code starts at $8100, but this is inside BASIC's 
default memory range, which extends up to $9FFF. Also, the improved front-panel simulator creates a 
lot of temporary strings compared to the first version. These grew downward in memory and completely 
clobbered the 250 bytes | had entered! 


So | lowered the top of BASIC memory, and started all over again. 


v VICE: C64 emulator —- + X 


The second time doing this, at least, | was able to enter the bits much more quickly; | had had practice, 
and had a block of time to myself that | could dedicate to it. And when | reset the address to review the 
code, it was, in fact, the code | entered. 


Well, mostly. | skipped a byte about 80% through. So, | re-entered the last 20% and reviewed it again. In 
the second review, | found one wrong byte, but thankfully it was all in sequence and | didn't have to shift 
anything. 


Satisfied that what was in the computer matched what was written down on paper, | reset the address to 
the beginning again and... executed! 


And nothing happened. It just hung. 
Thus, the debugging began. 


| pressed RUN/STOP+RESTORE and re-RUN the front-panel simulator — the moral equivalent of 
pressing a Reset button on a single-board computer which resets the CPU to a known state without 
affecting the contents of memory. 


But how to debug something like this? 


| looked back to the listing on paper and traced the execution path through it, as best | could, by hand. | 
couldn’t see where there was a problem. 


The first routine the code calls is WRITE_PROMPT. In the front-panel simulator, | advanced to the 
WRITE_PROMPT routine and executed it. And | got this: 


¥ VICE: C64 emulator —- + X 


addddiddddtdtidciddtindtintddnnndddntnnnddnaas 
adddtidddtidtiddidcidtidciddcidtidcidtidctncndcddadsadaa 
adddtiddiddidtititiddiddtitidititdtitddititiddtitthtiitidtiddtiditidl 
atddddtiddiddidtididddidtiddiddiddtinditidtdnntntdnnnaa 
fddddddtddtdtidcidctiditidddiddctidcindcidtidctnttnddnsaa 
aaiddttidddiditdtitidtididtiti§iidtititidtitititvidtdttiddtiddtititil 
taddttiddidtitdtititidiititdtidtidtitdtititiddititidtidtiddtiditial 
addddiddidddiddtiddidtidtidtdiddidtiddiddiddidtidddiddiddadad 
addddiddiddtdtidcidtindtinntddndntdddntnnnnaas 
tidddtiddiddidtiddidddiddtidtidtidtiiddtiddditititiddtiddtiditidiatia 
tdidddtiddtiddididdidititditidddiddtitdididitiddiddtiddiddidtidtiddtiddidt 
addddiddidtidtidciddidtincddnntdndnnnndnnnaaa 
adddtiddidtidtiddiddcidtidciddcidtindcindctidcindcndcndddsnaa 
tdiddttitddiddtittitntititittiidtititi#tititdtitidddddddtiddiddddd 
atddddtiddiddtdtiddidddiditindcidtidtintdtdnnnnnnnsaas 
aidddddddddidtidcidctidtindcidtidtinddndtntnnnaaa 
tdididtiddiddtitd@dititiddtidtitittidtitdtiiditititidtitititttidtiditititidl 
taiddttiddidtidtidtitdtitditit#ti$dtitdtidtidditddtitididtidtidicidicia 
addddiddiditidtiddidtidtidtiddddididdiddidtiddciddiddndnddad 
addddiddidtidtidcidctidtincidtdtntdndnnnnnnaas 
tdiddttiddiddidddihaidddiddidtiddddddiddiddtidididdidtidcidatd 
tdidddtdditddditiddtidtididtitididtitdtitddidtiddtiddcidddidddiddd 
addddddtddtdtidciddidtincdtnintdddnnnntddnaas 
adaddtidddtidtidddtidtindctidtndtintidtdtntntdnsa 


Yeah, no, that definitely wasn’t in the spec. 


A mild panic set in. The bug could be anywhere. | might've written down the wrong binary for a hex 
value; | might’ve written down the wrong hex value for an opcode, or | might've made a programming 
error in the code itself. 


| had just finished entering 2,000 bits on a simulated front-panel — for the second time! — and | was in 
no mood to spend the rest of the weekend, or possibly the rest of the RetroChallenge, poring over my 
program. 


So | took a bit of a mulligan. It was a small thing, and | could rationalize it by saying “let’s pretend there 
are 16 green LEDs on the front panel for the address lines” or something. But still, I’m not proud of it, 
and it should count against my RetroChallenge score (however vague and nebulous a concept that may 
be.) 


| converted the address of the OUTPUTLN_TTY routine to decimal (33153), dropped to BASIC, and 
PEEK’ed that address to see what byte was there. The first instruction of OUTPUTLN_TTY is LDA #$00, so 
| was expecting to see 169 ($A9), but... 


2 VICE: C64 emulator —_- + 


Noticing that the byte just before OUTPUTLN_TTY was $81, it occurred to me: maybe | made a mistake 
assigning addresses to labels. 


So | read over the code again, and, indeed. 


$139 RD.HK. JSR $813¢ ad 3¢ 81 
$13R PS.HX. LOY #$¢¢ Ag $¢ 


See the problem? 


So! A bit painful that this mis-numbering happened so early in the code, but, there was nothing to be 
done except to go through it all and correct the addresses: 


$8ido 
ties 
W166 
61¢8 
LIGA 
SigD 
B19 
8113 
G15 
19 
BIA 
uc 
sue 
ial 
8123 
#125 
irs 
BIBA 
Tiac 
giar 
$13¢ 
$132 
$135 
B13¢ 
$138 
$139 
fisc 46 
Ti3E OD 
gin He 


MAIN 


pisP 


ISR $8] 36 79 $1 
IsR $tigeras) Ag 45 FI 
LOA #¢¢) Aa gr 
STA $FE vs Fe 
Tsk S$tu¢g ae 6 HI 
Ive $tige | 4c Ge #1 
LDA Scag AD ¢¢ <¢ 
cmp #$4! co 
BNE $63 a 
IMP $BIAT AS 4c AB SI 
CMP 4$4D c4 40 
BNE $03 De os 
IMP $FiaX I wc BB FI 
cme #957 c? $7 
BNE $¢3 | De g3 
IMP $9ic4cs 4C cy By 
CMP &$47 cq 47 
BNE $63 De 93 
gue ($0er8) Gc FB og 
RTS 6¢ 

Loy $fe AM FE 
Loa Seg¢,y 87 69 co 
wy cy 

STY SFE a4 FE 
RTS oe 
ISR $8130 0 ag 36 8 
Loy #$¢¢ Ad a 


Che $BiER,Y De ER gy | 
BNE $¢a oe ga 


CoboooceO 
Ool Cooee 
1OLOloe| 
loooeSlot 
O616 O9e6 
O1ostitoe 
moro ridt 
1100 48oe! 
1tol Ceoo 
oleoitce 
1100 Loo; 
1fo! Seco 
o1mciioo 
11eoloot 
to] coee 
oleco itco 
l1oc tect 
ttoloveo 
oucitecs 
Olfocces 
1010 S100 
por, toot 
1400 [oeo 
lowooroo 
Oltoeceo 
oo19 0000 
1O10 0000 
1iol 1ooy 


1101 0000 


Ont ocean 

1ool Oo@ 

Ocooo0e| 

(titties 
Coe \ocVe0 
Qeen0ge0 
Oteoseco 
© 100ces( 
oeecco 
fore bfeo 
Oreo 1190/ 
coco cel 
por corm 
sietoct 

eoooooil 
1 10eeleg 
o1cootlt 
ecoeoolt 
tetttort 


hhriilito 
6000 coco 


Oo ecco 
Qoo00000 
1Lio1oee 
o°0goolo 


1000 ooe! . 
[occ ooo] - 


leeoooco| . 
1CeO Coe! | 
11ooceco - 


loveoeo! - 
todgeee! . 
1eo0 coo| 
occoocee 
1100 C000 . 


toeoooed! . 


1900 S80} 


Qi4c RD. 


GSS weer. 


TYA 
RTS 


Iny 

cey #$1¢ 
Bue $F4 
Loa S$e¢ 


RTs 

Tsk $9139 
ASL A 
ASL A 
ASL A 
ASL A 
STA $FD 
ISR $et39 
ORK $FD 
RTS 

PHA 

LsR A 
LSR A 
LSRA 
LSR A 
TSR $€le4cs 
PLA 

AND #$¢F 
TAY 


LoA $8IER,Y 
LDY $Fe 

STA $<6O¢,y 
INnY 

STY SFE 
RTS 


oo 
= 


SRSSSSREsVass 


locticoco 
OLLoeooo 
WwooTeco 
tieceoce 
lol coco 
to1oles| 
©1110 ceoe 
Oo1Ooceo 
ooo Lele 
Seooe loc 
Gece (oro 
Coo@lore 
(coolio 
Colo ooeo 
coco ote) 
o11e cece 
Ooo | ceo 


S400 Cowes 
Seocere 
Sik ceess 
P+ Oo cooed 
coio ccoo 
Clic 10°00 
oocre tool 
lolo 1000 
trotl 1eot 
lolo c160 
1oo{ toel 
lice tooo 


tooo o1 00 
Olle ©9000 


oooloo00e 
t1etetoe 
00000000 


Corl loos 


tititior 
ooltoot 
teateect 


electole 
Clectolo 


Stlooicic 
Cloolcio 


CUColeg 


Sooo 


{iio loee 
tetetito 
00 600880 


ieee 


loeooee| - 


1aoceoo! 


teoooce| . 


tLooo0co 


wR Pe. 


wr. TtY 


LDA #fee 
STA SFE 
LDA $FC 


Tse $88 se 


LDA $F 


TsR $8158 Sc 


PSSRZRRREAT 


love teot 
[oe Olol 
toroclot 
00(0 0000 
lolooict 
O0]o oec0 
1olo tect 
Ole cece 
{Olo eeec 
sorlicoer 
oolcccco 
1teoteeo 
thoowes 
trol Cooo 
O1le ooeo 
tole eoeo 
6010 G9 e00 
1001 | oo; 
1100 1000 
[reetool 
1101 O0eO 
1001 [oor 
100 1100 
Gold b0e0 
looootel 
Cole oo00 
leccolc| 
o1loocco 
folo ooo 
1016 C0 00 


Seco o0eo 
tite tiro 
tritthoo 
o1ol teed 
ttryt tot 
olol Lom 
cooceltol 
C19 tole 
Odec0000 
eoocsccoo 
tior ooo 


Coco 110! 
ttitotor 


Qocooocoee 
1rediert 
ooa0 Seco 


occotlo| 
Cit otol 
oGooco00o 
1t6loero 
cloollog 
rrittites 
O10 110@ 
ition 


Ooo! Goeo 
Oooocceo 


1000 Coot 
loee ooot 
joes eco! 


11ec Coco 
faeces 


rouveetr 
{teooood 


ileoedoo 
tirtevet 
loooccol + 


icec cool - 


PIG? $O8e Loa (7B), ¥ BI OFS lotloool tettton ° 
7 888 J5R Seisese | AH SE BI COlCCe0o = Clot 14RD = | Com o00 
c G88 TsR $fiowoc | od PB BI Soeteoceo 11011@eD = 1Oeoceo! 
Fe ise Dex cA Troctoro 
tice giee BNE $F3 Dy FR LO] Oooo) = tt F Oor bd 
2 sie ee S$siersa | uc gn 8! Oleetioe l000cap loeccoce! 
SicS Gee wine Loy SFE AY FE [ole C100 littittoe 
7 Seo LpA $cée¢,¥ Bq @¢ cg lon ioctl Coodesco § loc oero 
A $ica CMP #800 cq @D lLeotool Oooo {lol 
. aan oo $91 4 gI L1eCleeeO = PED oO! 
F cE IsR $tec 40 a 40 $I le thr Ole 110g 1ooceoce! P 
RIOD = Siwl Loy #$e¢ Ad 1Ol8cc00 §=— SECO eD*O 
4 103 STA ($F8),Y aU FS loo! Soo} tettton 
6 gs TSK $RIDB Dc | ag DS TT OCIOOCCD §=ttOlIeeh leeoeoo; 
2 sof Imp $8ieHes | He CH BI C1OC110G Ee olem eee C00! 
foc } tg mR os or | O01 to”00 é' 
D DC LDA AS FB 
[im mee the) |6| he Soe , 
iad 4 oo pe 8S FE | 1000 ere) = tN EN TON 
c AS Fe 
3 t64 Ave ates A | rhs {hittsoco a 
7 Sree STA $Fe Ss leewatee 
2 tes RTS Ge  OL16 e000 
TicA See Hea d3¢ 3 | aait ebes OO ool 
$3: 31 ; Olcocco( 
$32 Con aers Gjeooe1o 
$33 bie OO1! Colo Siecoolt 
3 33 Coll oot; 
a | 34 Oot! olcoe O1ec oloo 
% 35 Coil Oo} Olocoici 
37 36 | Goll otto 
37 oom ous O1ooollo 
$39 \3¢ Oo tooo 


And then, back to the front-panel simulator. Reset the address to the beginning. Keep advancing the 
address until you get to the next byte that needs correcting, enter the new byte, repeat. A little nerve- 
wracking, but not terribly difficult, because | was getting pretty used to this by now... 


Then, reset the address to the beginning again, and... execute! 


v VICE: C64 emulator —- + 


Hey! That looks... like what | expected! Let’s see if it works: 


sf VICE: C64 emulator —= + 


Do 
KOO 
® 


48126958i1AS68i185F E2616814C8esi 


bbe 
® 


23456789ABCDEFF 


8 
i 
8 
8 
i 
i 
8 
8 
is 
ci 
is 
8 
i 
i 
8 


8 
8 
8 
7 
8 
8 
8 
i 
3 
8 
8 
i 
8 
8 
6 


Fr OBOE ZO Rs 


23456789ABCDEF F 668866666 66666 


wiles 
® 


BOaoDo 
_ 
® 


It works! It works! 
This is a very nice feeling — one that makes up for the earlier disappointments. 
So now... we have a machine-code monitor! It’s crude and ugly, but it does the trick, and it’s small — 


250 bytes, or maybe 251 bytes now, because of the addressing correction? I’m not sure, but it’s still less 
than 255 bytes, and that’s great. 


ENTRY POINTS IN StTU-NON (connecteD) 


MAIN $8102 
DISPATCH $S11¢ 
READ. CHAR $313¢ 
READ. HEX $ 3139 
PARSE_HEK $813¢c 
READ_ BYTE $ 814D 
WRITE. BYTE $31Sc 
WRITE_ HEX $8165 
WRITE..CHAR $316R 
WRITE _ PROMPT $3174 
OUTPUTLN_TTY $3192 
OVTPUT_TTY $3187 
INPUT. TTY $8195 
SET- ADDR $Z1As 
READ_MEM $3183 
WRITE_MEM SICS 
INCR. ADOR BIDC 
HEXDIG(TS $ SIEA (not callable) 
LINE $ COBO 
ADDR (—Le) $ FB 
AvpR- HI $ FC 
THP_A $ FD (only used in READ. BYTE) 
LINE _ OFF $ FE 


’ 


We're not done, though! A machine-language monitor is a kind of a programming environment, but it’s 
not a very good one. We won't have to convert anything to binary, and entering lines on a keyboard is a 
lot easier than using front-panel switches. But we do still need to hand-assemble our code to hex, and 
compute addresses and so forth, which means we'll still be using paper a lot. 


Here’s an example of how much easier it will be, though. It’s a fancier version of the warm-up exercise, 
the “echo” program. It displays a sort of prompt between lines, and lets you quit by starting the line with 


a period. 


$82¢¢ EcHo2: LOA #¢ AY og 
o- STA LINE _ofe 8S FE 
4 LDA #°>? AY 3E 
6 JSR WRITE_cHAR 26 68 BI 
q JSR OVTPUTLN_TTY 2 BA QI 
C JSR IWT_TTY og 95 Bi 
F LDA LINE AD @¢ cg 
a1 2 CMP #°. cq o2E 
y BNE CONT DY gl 
G RTS 6¢ 
§R1 7 CONT : JSR OVTPUTSyY_ Try 2G & $I 
Z21A JmMPp EcHol 4C GO FL 


Note that, since we don’t have to convert to binary anymore, we can format the listing on paper more 
compactly. Entering and reviewing and running it is a matter of a few monitor commands: 


¥ VICE: C64 emulator —- + 


So: ee sone 


6S5SF EASSEZSEBS8126828126958i1ADe6CE 
ED68i1662687814C8682 


BS5SF EASSEZSEBS126828126958iAD 


6CS2ED661662687814C868826866686 


BNN@ FO BNKOrOON® 
® 


@o0M 809 Seonneooo 
fan) 


68 
As 
82 
WA 
82 
WC 
82 
As 
82 
M 

MA 
82 
M 

Me 
82 
As 
82 
& 

> 

i 


And we test it a bit to make sure that it works as designed... 


¥ VICE: C64 emulator —_ + 


Renee 


8 
A 
8 
& 
> 
H 
H 
> 
E 
E 
> 


Bo Ve4+VEEv 


I’m quite happy with this! 


Now, to design and write a better programming environment that we can enter into the computer using 
SITU-MON here... 


SITU-SOL 


July 26, 2015 


SITU-SOL 


THE DIFFERENCE BETWEEN A “Low-Levet” 
PROGRAMMING LANGUAGE AND A “HIGH- LEVEL” 
ONE '§ NOT CLEAR-CUT, BUT ONE THING 
THAT MOST “HIGH-LEVEL” LANGUAGES Do 
IS TO Allow THE PROGRAMMER To 
DEFINE THEIR OWN IDENTIFIERS USING 
A (Mostcy) FREE CHelcE oF LETTERS 
AND NUMBERS, |MPLEMENTING ‘THIS 
FEATURE MEANS STORING THESE SYMBALS* 
IN A DATA STRUCTURE, AND RETRIEVING 
THEM FROM “THIS STRUCTURE AS WELL. 
WE'LL IMPRovISE A SYMBAL ~ ORIENTED 
LANGUAGE ARouND THIS, AND CALL IT: 
S(ITU~SOL. 


ee ee cv 


SINTAX OF SITU-SOL 


A SlTuU-SOL PROGRAM CONSISTS OF A 
NUMGER oF LINES, WHICH MAY BE ENTERED 
INTERACTIVELY. THE FIRST CHARACTER OF EACH 
LIVE HAS A SPECIAL MEANING: 


L Symbal symbal ... symbal 


— ComPILE THE SYMBALS Te 
THE COMPILATION GUFFER. 


] Symbal 
- DEFINE A NEW SYMBAL, 
USING THE CURRENT contents 
OF THE ComPiL. BUFFER. 
F ne - RESERVED FoR FUTURE Exe. 
° - Quit SiTU-set (AND RETURN 


To SITU-MOoN, IF APPLICABLE) 


1F THE LINE BEGINS WITH ANY OTHER 
CHARACTER, (tT 1S NOT SPECIAL, IT (tS SIMPLY 


Symbal Symbal ws Symbal 


THESE SYMBALS ARE COMPILED To THE BuFFER 
AND IMMEDIATELY EXECUTED CIMMEDIATE MoPE.) 


COMPILATION OF SYMBALS 


SOME SYMBALS ARE SPECIAL FORMS WITH 
SPECIAL MEANINGS: 


+ x y - READ xy AS A BYTE (To 
HEAADECIMAL DIGITS) AND LOAD 
THAT BYTE INTO THE A(cuMULATEA, 


2 symbal - EXECUTE THE NEXT SyMBAL 
ONLY IF THE ZERo FLAG IS 
NoT ser. ("iF") 

symbal | - EXECUTE THE PREVIeUS SYMBAL 


AGAIW (AND AGAIN...) IF THE 
ZERo FLAG |S Not SET. 
(* REPEAT”) 


SYMBALS BEGINNING WITH < OR > HAVE A 
SPECIAL MGANILG WHICH IS RESERVED. 


OTHERWISE, THE SYMBAL IS LOOKED UP IN THE 
SYMBAL “TAGLE, ANO “THE DEFINITION ASsocIATED 
WITH “THAT SYMBAL (tS EXECUTED. IE THE SYMBAL 
COULD NOT BE FOUND IW THE SYMGAL TABLE, 
THAT'S A COMPILATION ERROR. 


STANDARD _SYMBALS 


WE WILL NEED A SET OF PRE-DEFINED 
SYMBALS IN ORDER To Do ANYTHING INTERESTING 
IN THIS LANGUAGE. 


UNFORTUNEATELY, | HAVENT REALLY WORKED OUT 
WHAT THAT SET witt &E, YET. 


WE'LL DEFINE SOME SIMPLE AD-HOC SYMGALS For 
TESTwG PURPOSES LATER ON... 


FOR NOW, LL NOTE THAT WE Could DEFINE A 
SET OF SYMBALS THAT OPERATE ON A STACK, 
MAKING THE LANGUAGE VAGUELY FORTH-Like. 


OR, IF WE DEFINE A TAPE-LIKE STORAGE 
FAUILiTy, AND HAVE SYMBALS LIKE: 


... THEN WE OUGHT To BE ABLE To Cope 
ANY TURING MACHINE IN SITU-SoL, MAKING 
THE LANGUAGE ‘TURING- COMPLETE. 


_[MPLEMENWTATION NOTES. 


mi VE EFIMITION OF SYMBAL 
mm MAGNE CODE) 


LENGTH OF DEFINITION 


+ READ BYTE PROM THERE, “Avo” IT witH 
2 ye a. PRott_ es ADOR ESS. stant 


: nm aust READ “Lew a 


a a 


Now, the program listing! No, wait — | don’t want you to get the impression that this just appeared fully- 
formed on paper. So, first, I'll ask you to imagine about 30 sheets of paper that looked something like 
this: 


OK, now the program listing! 


RESET_ STAB_PTR: 


INCR _Stag_ PTR: 
AbD. A_STAB_PTR: 


AD?_TO.STAB_PTR: 


SUB_ STAB_PTR: 


LDA #$90 

STA STAB.PTR.LO 
LDA #$94 

STA STAB_PTR- HI 
RTS 


LDA #301 
STA STABLDELTA 


cLes 
LDA STAB_PTR_LO 
ADC STAB_ DELTA 
STA STAB_PTR.LO 
LoA STAB_PTR_HI 
Avc #$¢¢ 

STA STAB_PTR-H\ 
RTS 


SEC 

LDA STAB_PTR_LO 
SBC STAB_DELTA 
STA STAB_PTR.LO 
LDA STAB_PTR_HI 
SBC #$ 06 

STA STAB_LPTR-HI 
RTS 


$324 


ru mM 


$330 
n 


o~ 
u 


$337 


PEEK_STAB: 


WRITE STAB: 


LookuP_SYMBAL: 
Loop: 


ENO_oF_STAB: 


LDY #$0¢ 

LvA (STAB_PTR), Y 
STA STAB. BYTE 
RTS 

LDY #$¢¢ 

STA (STAB. PTR), Y 
IMP INCR STAB_PTR 
JSR RESET_STAB_PTR 
JSR PEEK STAB 
REQ END.OF_STAB 
JSR MATCH. SYMBAL 
BCS Loop 

LDA #$02 

JSR Avd-F-STAB_PTR 
CLC 

RTS 

SEC 

RTS 


3s 
& 


Seesees 
2 8 8S 


¢34p MATCH_SYMBAL: LDX LINELOFF 
9345 Loop: JSR PEEK_STAB 
7 AND #$8¢ 
uy BNE CHECK_END 
LDA STAB_BYTE 
CMP LINE, x 
BNE MISMATCH 
JSR INCR_STAB_PTR 
INX 
IMP Loop 
CHECK-END: LDA LINE, x 
CMe #$2¢ 
BEQ MATCH 
CMP #$6D 
BEQ MATCH 
MISMATCH: JSR PEEK_STAB 
AND #$3¢ 
BNE SKIPLENTRY 
JSR INCR.STAB_PTR 
JMP MISMATCH 
MATCH: $TX LINE_orF 
EL.é 
RTS 
SKIPLENTRY: JSR INCR_STAB_PTR 
JSR PEEK_STAg 
STA STAB_DELTA 
INC STAB_DELTA 
ISR ADD.TO_STAB_PTR 
SEC 
RTS 


av wa® 


6. 


$3 


6 


~ 


FeamnmmMonw oe scPpPnrdWaoitit = 


moras 


A 
w 
oe 


BS38F 
q| 


4 


PEEK_LINE: 


$375 RESET_LINE: 


q 


$39A 
dD 


> 


B3AE 
BI 


5 


B38 


SKIP_ SPACE: 


READ_ ARG ° 


LDY LINE_oFF 
LpA LINE, Y 
RTS 


LDA #$0¢ 
STA LINE.oFF 
RTS 


ISR PEEKLLINE 
CMP #$¢D 
BEQ CR 

CmP #$2¢ 
BEQ SPACE 
CLC 

RTS 

SEc 

RTS 

INC LINE_OFF 
IMP SkIP_SPACE 


JSR READ_BYTE 
STA  ARG_HI 
JSR READ-BYTE 
STA ARG_Lo 
RTS 


%¢ 
FE 


ce 


e 


E 


8354 EMIT_REPEAT: 


RESET_EMIT: 


EMIT_BYTE:: 


EMIT. CALL: 


EMIT LIF: 


LDA 
STA 
RTS 


LOY 
STA 
INC 
RTS 


LDA 
JSR 
LDA 
JSR 
LDA 
JMP 


LDA 
TSR 
LDA 
JSR 
LDA 
SMP 


LDA 
TSR 
LDA 
JSR 
LDA 
JMP 


#$G¢ 
EMIT_oFF 


EMIT_OFF 
EMIT BUF, Y 
EMIT_oFF 


$$a¢ 
EMIT_ BYTE 


STAB_PTR_LoO 


EMIT_8YTE 


STAB _ PTR_H| 


EMIT_BYTE 


#$EA 
EMIT_BYTE 
#$FO 
EMIT. BYTE 
#33 
EMIT_BYTE 


#$B9 
EMIT_BYTE 
#$EB 
EMIT _ BYTE 
$$ER 
EMIT.BYTE 


Cl 


83 
$3 


$3 


&3 


83 


$3 


83 
83 


83 


$3 


F3 
5 
8 
A 
D 


EMIT. ConsT: 


EMIT_LOAD: 
EMIT. ARG: 


EMI(T_SToRE: 


WRITE. PROMPT: 


LDA 
JSR 
LDA 
JSR 
LDA 
IMP 


LDA 
JSR 
LDA 
JSR 
LDA 
JMP 


LDA 
SMP 


JSR 
LDA 
TSR 
LDA 
ISR 
IMP 


#$A9 
EMIT_BYTE 
ARG_LO 
EMIT_ BYTE 
#$EA 
EMIT. BYTE 


#$AD 
EMIT_BYTE 
ARG LO 
EMIT_8YTE 
ARG HI 
EMIT_BYTE 


#$8D 
EMIT_ ARG 


RESET_LINE 
#70 
WRITE_CHAR 
#°K 
WRITE ~ CHAR 
OUTPUTLN TTY 


4C 


$2 


$3 


83 


S4AG 


eno 


2 w 
TA HRIKVVOsS oI o 


on 
—- Mw oo Ww T 


Py 
elke 
t~ 


TOPLEVEL: 


NEXT: 


NEXT: 


NExT: 


NEXT: 


WRITE_P ROMPT 
INPUT_LTTY 
RESET_LINE 
PEEK_LINE 
+’. 
NEXT 


#°L 
NEXT 
LINE _ OFF 
SYMBALIZE 
TOPLEVEL 
#°] 
NEXT 
LINE_OFF 
DEFINE _SYMBAL 
TOPLEVEL 
#°/ 
NEXT 
LINE OFF 
REPLACE_REFS 
ToPLEVEL 
SYMBALIZE 
EMIT BUF 
TOPLEVEL 


SUG 
8407 


> 


I 
“= 9 Ti © 


© 
mo Qam Ge ao 


Awami —& 


> 
rco-nrens 


S4A7 


SYMBALIZE: 
Loop: 


NOT.EOL: 


NEXT: 


NEXT: 


NEXT: 


ISR 
ISR 
Bcc 
omMP 
JSR 
CMP 
BNE 
INC 
JSR 
IMP 
CMP 
BNE 
INC 
ISR 
IMP 
CMP 
BNE 
INC 
JSR 
STA 
JSR 
JMP 
CMP 
BNE 
INC 
JSR 
JSR 
IMP 


RESET EMIT 
SKIP_ SPACE 
NOT_EOL 
EOL 
PEEK-LINE 
#°? 
NEXT 
LINE. OFF 
EMIT_IF 
Loop 
#°! 
NEXT 
LINE OFF 
EMIT REPEAT 
LOopP 
+" 
NEXT 
LINE_oFF 
READ_ BYTE 
ARG _LO 
EMIT.CONST 


NEXT 
LINE_oFF 
READ. ARG 
EMIT_LoAD 
Loop 


83 
$3 


BY 
84 


S4AA NEXT: 
c 
E 
BO 
3 
G 
4 NEXT: 
as 
E 
Cl 
u ERROR: 
$407 EOL: 
9 


S4Cc REPORT_ERROR: 


E 
F 


da 


S408 


#”"> 

NEXT 

LINE OFF 

READ. ARG 
EMIT. STORE 
LooP 
LOOKUP_SYMBAL 
ERROR 

EMIT. CALL 
Loop 
REPORT_ERROR 
#$ 6g 
EMIT_BYTE 


LINE. oFF 
RESET_LINE 
#°? 

WRITE_ CHAR 


WRITE. BYTE 
OUTPUTLN.TTy 


BHDE 
El 
3 


DEFINE. SYMBAL: 


NOT FOUND: 


Loop: 


SCANNED: 


COPY _ Loop: 


LOokuP_SYMBAL. 
NOT.FouND 
REPORT_ERROR 
#300 
TEMP.LENGTH 
PEEK LINE 
#$9D 
SCANNED 
#$ 29 
SCANNED 
WRITE_STAB 
LINE_OFF 
TEMP_LENGTH 
Loop 
TEMP_ LENGTH 
#$ 3 
WRITE. STAB 
EMIT_OFF 
WRITE-STAB 
#$ 09 
EMITBUF, ¥ 
WRITE_ STAB 


EMIT_oFF 
CoPY. Loop 
#300 
WRITE. STAB 


RESET_STAB_PTR 


$3 


34 


$3 


83 


Cl 
83 


83 
83 


All written and hand-assembled! 


At this point it’s handy to have a list of the entry points, so | wrote that up too: 


ENTRY POINTS in SITU-SOL 


RESET_STAB_PTR $930¢ 
INCR.STAB_PTR 3309 ADD_A.STAB_PTR 
ADD_TO_STAB_PTR g36p * $308 
SUB_STAB_PTR 8318 
PEEK_STAB $3249 
WRITE _STAB 8330 
LOOKUP_SYMBAL $337 

MATCH. SYMBAL S$ 34D 
PEEK_LINE S33F 

RESET _LINE $3495 

SKIP_SPACE 839A 

READ_ ARG S3AE 
RESET_EMIT 8389 

EMIT_BYTE 338E 

EMIT_ CALL $3CG 

EMIT_ IF 83D5 

EMIT REPEAT Q3E4 

EMIT _ConsT S3F2 

EMIT _LOAD $402 

EMIT ARG $4gu 


EMIT _ STORE G4! 


WRITE —PROMPT $ 9416 


TOPLEVEL B4AG 
SYMBALIZE 84YC4 
REPORT_ERROR S4CC 
DEFINE_SYMBAL S4DE 
TEMP_ LENGTH SED  — (TMP_A in SITEMMON) 
STAB_PTR[_LO] SOA 
STAB_PTR_HI 8B 
STAGB_ DELTA Gc 
STAB — BYTE OD 
ARG_LO OE 
ARG _HI OF 
EMIT_OFF 1¢ 
EMITBUF $ CI O¢ 
STAB_ BASE $ 69 0¢ 


Now, to enter it... luckily, entering hex digits with SITU-MON is a lot easier than entering bits using front- 
panel switches. 


_ 


") VICE: C64 emulator 


BSSGARASSSSSEBES 

i8356c 
SSBAGSECSSSEAASSBESESSIEBES 
JBARESSCSSGAASSBESSSSSEBES 
6BiGASSEDES 

69i18AACESS3 

683262983F 68C264D83B6F GASG2 
D83i18663866 


OVOOO02 02090000000 


Ph Et det oo HE ttf Ort tot | 


68 
AS 
83 
HWA 
83 
WA 
83 
Wi 
83 
W3 
83 
WA 
83 
WA 
83 
H2 
83 
H2 
83 
i 


VICE: C64 emulator 


639i168A4CESS83 

683262983F 66C264D83B6F GASG2 
6D83i186863866 
E2629832986D66EAS6DDDE6CED6i122686983 
C4F S3BD66C8CS326F 61 i1CS6DF 66D 
S83S298GDGGA269834CEF SSS6FEIS66 
S83262983856CE6SC266D833866 
EBSS6C666 

6SS5FE66 

FS3CS6DF 686CS26F 6641 8663866E6FE4C9A8 


Bwow 
OnNoo 


saa 


DSisSeF 264D8is856E6e6 


BOD BOOLVSHOHO70N7 


Miho Nabudananamusancnce 
CAM BDOUNNOON NSN 


_ 


") VICE: C64 emulator 


FS3CS6DF 666CS26F 6641 8663866E6FE4C9AR8 


DSisS6eF 264D8is856E6s6 

6851666 

639366CiE6i666 
B26BES3ASGAZBBESSASGBACBESS 
AZBBESSASF G26BES3ASG34CBES3 
B26BES3ASF AZGBESSASERACBESS 
S26BES3SASGE26BES3SASERACBESS 
D26BES3ASGE26BES3A5GF 4CBESS3 
D4C6484 

S83AS4F 266B8iAS4B266B8i14C8281i 


NOKOrCOONOMOSTOOLDOMOD @0 
ANOMGKHDSVDSWOAMUNAMSoOLM oD 


83 
H2 
3 

83 
H2 
83 
WA 
83 
WA 
83 
WA 
83 
WA 
83 
HWA 
83 
WA 
84 
WA 
84 
WA 
84 
H2 
84 
a 


= 


VICE: C64 emulator 


D26BES3ASGE26BES3A56F 4CBESS 
D4C6484 

J83AS4F 266B8i1AS4B266B8i14C828i 
684269581269583268F 8S3CS2ED86i66 
BDSGSEGFE2664844C2684 
DDSGSEGFE2ZS6DES44C2684 
FDOSSEGFE2836844C2684 
4842666Ci4C2684 
SSS2G9AS39GG34CCTS4268F S3CS3F DEES 
E26D5834C6 784CS32i1DSG8EG6F E26E 483 
T84CS23DG6DEGF E264D8i1856E26F 383 
TS4CS3CDSGEBEGF E2GAES32662844C6 784 


3A 
ii 
33 
i6 
63 
26 
6i 
37 
35 
43 
33 
4F 


3 
> 
8 
6 
8 
7 
6 
8 
Cc 
3 
Cc 
A 


me Thea MaNaNan nono nnanasad 
DPHMOHNIMVBAHAN 


VICE: C64 emulator 


S83269AS396G34CCT7S4268F S3C33F Dees 
E26D5834C6784CS92i1DSG8E6GFE26E 483 
T84CS23D66DE6GF E264D8i1856E26F 383 
TS4CS3CDSBGEBEGF E26AES32662844C6 784 
EDGGBEGF E26AhE832611844C6 784 
TSIBSSG626CE834C678426CC84AS6B4CBES3 
E48269583AS93F 266B8i168265C8i4C828i 
TS3IBSG34CCC84A9G685F D 

FS3CS6DF 6GECS26F 66A 

SBS3SEGFEEGF D4CEAS4ASFD 
B6263683A516263683A26BBDE6Ci 
BS3ESE 41 6D6F 5ASGG2636834C8883 


H26B 
8476 
WE GE 
8487 
H4C6 
8438 
H4C6 
84AA 
WC33 
84B3 
H263 
84cc 
HWASE 
S4DE 
H263 
S4EA 
H268 
84F5 
H263 
856i 
W833 
$316 
H263 
8526 
i 


All done! 
Of course, | made several errors. 


| caught one error while reviewing what | had entered with the M command. | had simply mistyped a 
line. That one was easy to fix. 


Other errors — | had to test the program first. 


And in order to test it, | needed to have a symbal table for it to work on. | made one up with two very 
simple “commands” whose effect would be both obvious to see, and non-intrusive on the rest of the 
system. | decided to have them call two of the simpler routines present in SITU-MON (WRITE_PROMPT 
and INCR_ADDR). (And yes, you’re right, they should really be called $ADDR and $INC, with the dollar 
signs — thank you for paying attention to the spec. But, this was just to test...) 


%2G¢ 


DEMO SYMBAL TABLE 


“ADDR #$84 #$04 
JSR WRITE_PROMPT 


RTS 


“Inc” #$83 #$04 
JSR INCR-ADDR 


RTS 


ESO 


4144 44 52 84 gy 


2 74 $1 
6¢ 


49 4E 43 
4 dC 3] 
Co 


09 


TEST DRIVER 


JSR 
JSR 
JSR 
RTS 


INPUT_TTY 
S¥m RESET_LINE 
SYMBALIZE 


ao 4S 
2G 495 
2g CY 
GY 


$3 OY 


8! 
$3 
84 


VICE: C64 emulator 


ECS26F 6G6AZESES3EGF EEGF DACERS4 
DES86263683A516263683A266BDE6 
B3E683E8E 41 6D6F 5A9662636834C86 


4445 2848426748166 
E43836426DC8i6666 


Mm 

MF 
84 
M 

MA 
85 
M 

Mc 
85 
M 

Ms 
83 
AS 
84 
Ag 
63 
H+ 
63 
HW 
63 
AS 
83 
WA 
83 
i 


| wrote the test driver so that | could A8200 then G in SITU-MON, enter a few symbals, and then, after it 
returned to SITU-MON, AC1@@ then M to look at the code it generated. 


One obvious symptom during testing was that SKIP_SPACE didn’t seem to do anything at all. It turned 
out that | had completely mis-assembled LDY LINE_OFF. (You can see this fix, and all the other fixes, in 
the listing above, if you look for them.) 


Another one was that the addresses in the generated code weren't right. It was emitting JSR’s to the 
size-part of the symbal table record, not the compiled code. It turned out that in LOOKUP_SYMBAL | had 
forgotten that ADD_TO_STAB_PTR gets its input from the memory location STAB_DELTA, and not from the 
accumulator. Luckily the fix was easy: add a new entry point called ADD_A_STAB_PTR just before 
ADD_TO_STAB_PTR, and call that one instead. 


Once | fixed that, | was able to compile simple “programs”: 


©©@©® VICE: C64 emulator 


INC INC ADDR 


INC INC ADDR 


BOOK HOD HOD HOHOMOOHOMDORMOM 
eo! a oc eee 8 ews 
re) 
m 
m 


There was still one more bug. The code generated when compiling a ! (repeat) was wrong — it was 
jumping one byte too far back in memory. Once spotted, that was another easy fix. And then... 


v VICE: C64 emulator - + 


wo 


% bow 


zN 
on) ' 


ADDR #i 


Bee Re eR eNOS EREROCRRERD 
N 


K 
i 
4 
K 
I 
4 
A 
K 
i 
4 
K 
I 
4 
A 
K 
2 


i] 


¥ VICE: C64 emulator —_ + 


N 


Bi in Pn sf si a sas in ns fi in sn sf fi in fn si in sin afin ND 7S D> 


I 
0 
A 
8 
8 
8 
8 
8 
8 
s 
8 
8 
s 
8 
8 
8 
s 
8 
8 
8 
8 
8 
8 
8s 
8 


WQWWWWWWWWWWWWNNNNNNNNN 
OBDPOVNMHULWVESNIMOOBMDONW + 


Huzzah! 


A moderate success. We have, on this emulated computer, a programming environment, hand-written 
and hand-assembled and hand-entered in hexadecimal (using a less sophisticated programming 
environment, which was itself hand-written and hand-assembled and hand-entered in binary using 
simulated front-panel switches.) 


But why do | consider this a moderate success rather than an unqualified success? Well, I’ll write a 
retrospective blog post on that topic shortly; stay tuned! :) 


Retrospective 
July 28, 2015 
What have | learned from this? What would | do differently, if | had to do it all again? 


Writer’s cramp. | really didn’t forsee that. | probably should’ve, but | didn’t. My wrist seems OK now, but 
last week it was definitely a bit ache-y, and | scaled back my ambitions a bit because | didn’t want to 
stress it too much. | guess it’s been a while since I’ve written this much. 


Uneven columns of text. | wrote the “nice” version of the code on printer paper placed over lined 
paper, to keep my rows straight, but | really should’ve used graph paper instead, to keep my columns 
straight too. Or @ French ruled paper, or a @ledger, or something. Also, putting more thought into 
choice of colours, etc., would’ve been nice. 


Assembler-ness in hand-assembly. | only flaunted the fact that | didn’t have to please an assembler’s 
idea of syntax a little bit: | used the same “local labels” like NEXT: over and over again, since | knew 
very well which one | meant at each point. An assembler program would’ve wanted me to call them 
NEXT1, NEXT2 or whatever, to keep them apart. | even used underscores in these labels, purely out of 
habit, but of course they weren’t at all necessary. | could’ve even gone much further -- | could’ve just 
drawn arrows from one part of the code to another. | kind of regret not doing something more “artistic” 
like that. 


No LEDs for the address lines. As | mentioned in the / love bits post, it would’ve saved a significant 
amount of debugging if | had known what address | was entering bits at. That’s a definite advantage the 
nice big front-panel of the @ Altair 8800 has over the austere front-panel of the 

@ 1802 Membership Card. But even showing the lowest 8 bits of the address would’ve been useful as a 
guard against this sort of address-misalignment problem. 


No padding between routines. | hand-assembled each routine to start at the very next address 
available after the previous routine. My excuse was that | didn’t want to have to enter more bytes than | 
had to. But this is a risky practice, because it’s quite easy to miss an instruction, or to want to insert an 
instruction later, for debugging; but if there’s no free space after the routine, you need to figure out what 
to replace with a JMP to somewhere else in memory (which will JMP back to continue the routine), then 
you need to find somewhere else in memory to put it... it’s a mess. | was lucky in that | didn’t hit a 
problem that required this. But it was luck. It would’ve been smarter to add 3 or so NOPs after the end 
of each routine, to make adjusting the routine easier, if needed. Even if it would’ve meant entering 24 
more bits each time. 


No comments. Yeah, that’s the thing, see. Writing documentation by hand is harder than writing code 
by hand because documentation is... sentences. The fact that you’re already writing out the “important” 
stuff seems like a good excuse to leave out the “non-critical” stuff like comments. But the comments are 
important -- especially in assembly language, where it’s really important to define what each routine 
expects when it is called, and what the rest of the program can expect when it’s finished (preconditions 
and postconditions.) If you fail to pay attention to these when writing code that calls that routine, very 
bad things can happen. Most of my first drafts did include scribbled preconditions and postconditions, 
but those notes didn’t make it to the final listings. 


The language is a bit goofy. And incomplete (no real standard library.) Well, | kept going back and 
forth on whether | should make a FORTH-like language or a LISP-like language, while at the same time 


wanting to keep it as simple as possible... and eventually simplicity won out. The resulting design for 
SITU-SOL has some similarities to Shelta, which | suppose isn’t surprising. 


OK, those are the basic ones. But the big one is: 


A programming language alone does not a 
programming environment make! 


See, one reasonable way to interpret the goal of this project of writing code by hand, is to write enough 
code by hand so that you don’t have to write code by hand anymore. 


But SITU-SOL doesn’t accomplish that goal. If you wanted to write a non-trivial SITU-SOL program... 
you’d probably want to write it out by hand first! 


( 
In other words... | probably should’ve just written a text editor instead. Maybe next year? 
Well, that’s not quite a fair assessment, either. Let me explain... 


In the modern world, we’d write our program in our text editor, and we’d assemble it with our assembler 
program, which is a separate thing. 


But uncompressed text takes up a fair amount of space, and on 8-bit machines, with their modest RAM 
and slow (or non-existent) persistent storage, that space is at a premium. So programming 


environments like BASIC do clever tricks like tokenizing the source code; an instruction like INPUT, 
even though it is entered as five characters, can be represented by one byte in memory, and displayed 
as those five characters again when the program is LISTed. Forth can do a similar trick (although | admit 
I’m not familiar with exactly how Forth is spec’ed to work, in this regard.) 


So, once | got SITU-MON in, | probably should’ve written a text editor, so that | could design and write 
and edit further programs directly on the computer, without using paper. 


But once | came across the idea that SITU-SOL’s code could be both compiled and tokenized (i.e., treat 
JSR $xxxx as a “token” that prints out the symbal-name just before $xxxx when it is decompiled, and so 
forth) -- that’s pretty neat, and | felt | had to go in that direction. (Maybe that’s how Forth works, too. | 
should look that up.) 


Anyway... 


To achieve this “edit directly on the computer, avoid paper” plateau, there are at least 3 more things the 
SITU-SOL environment should do: 


e Let you list the symbals that have been defined so far. (Like Forth’s WORDS, but | guess it would 
be called $SYMBALS here.) 

e Let you see the contents of a symbal’s definition, in a human-readable format. 

e Let you change the definition of a symbal. Or, if you can’t do that directly, let you replace every 
call to one symbal, with a call to a different symbal, in every defined symbal. (Then instead of 
changing a symbal, you write a new symbal and replace all the calls to the old one.) 


Now, | did design SITU-SOL to support these things... and | have written code to do these things! | 
include it below, for completeness. But | don’t think I’ll have the time (or the wrist-stamina) to hand- 
assemble it and enter it before the end of the month. 


The code for $SYMBALS: 


eo 


Dumping the contents of a symbal: 


WAUTE Stace : Los #day 
. se ware. awn 


a et SR. a a yo pl yeah Soe shoe —_ 


JSR WER StHe_eTR 
TSR READ _Sws 


STA SUS DELTA 


Aw #876 _ 
‘S14 Sws_DELTA ad 


T5R _ptR 


Replacing all calls to symbal1 with calls to symbal2: 


Calling those last two routines from the interactive prompt, with /D SYMBAL to dump and /R SYMBAL1 
SYMBAL2 to replace calls to symbals: 


So, if the point of this project was to write the code by hand, | can indeed say | have written those 
routines by hand! Not assembled, entered, or tested... but written, yes! 


Future work 


I've created a @ Mercurial repository on Bitbucket, which is mirrored in a @ git repository on Github, 
where I'll be placing the support materials and binary images from this project, and maybe in the 
future... other stuff, like a disassembly of the code that was entered. 


One of the reasons | entered SITU-MON at $8100 was because when the Commodore 64 is booted 
with an 8K cartridge attached, that ROM appears at $8000. | didn’t start right at $8000 because | 
wanted to reserve room for the header (the bit of ROM that tells the C64 "yes, this is a cartridge”) and 
some routines to do some initialization. 


So, one thing I’d really like to do is make such a binary image. Even if only to use it in the emulator. 
Because it’d be kind of cool to boot the machine directly into SITU-SOL. But that’s a bit outside of the 
scope of this RetroChallenge project. 


But after July ends.... who knows? 


